---
sidebar_label: Tables/Views
sidebar_position: 2
description: Manage tables and views with the Hasura schema/Metadata API
keywords:
  - hasura
  - docs
  - schema/Metadata API
  - API reference
  - table
  - view
---

# Schema/Metadata API Reference: Tables/Views (Deprecated)

:::caution Deprecation

In versions `v2.0.0` and above, the schema/Metadata API is deprecated in favour of the
[schema API](/api-reference/schema-api/index.mdx) and the [Metadata API](/api-reference/metadata-api/index.mdx).

Though for backwards compatibility, the schema/Metadata APIs will continue to function.

:::

## Introduction

Track/untrack a table/view in Hasura GraphQL Engine.

Only tracked tables/views are available for querying/mutating/subscribing data over the GraphQL API.

## track_table {#schema-metadata-track-table}

`track_table` is used to add a table/view to the GraphQL schema.

Add a table/view `author`:

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "track_table",
    "args": {
        "schema": "public",
        "name": "author"
    }
}
```

### Args syntax {#schema-metadata-track-table-syntax}

| Key                      | Required | Schema                                                                          | Description                                                                                                |
| ------------------------ | -------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| table                    | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                           | Name of the table                                                                                          |
| is_enum                  | false    | Boolean                                                                         | When set to `true`, creates the table as an [enum table](/schema/postgres/enums.mdx#pg-create-enum-table). |
| apollo_federation_config | false    | [ApolloFederationConfig](/api-reference/syntax-defs.mdx#apollofederationconfig) | Apollo federation configuration for the table                                                              |

## set_table_is_enum {#schema-metadata-set-table-is-enum}

`set_table_is_enum` sets whether an already-tracked table should be used as an
[enum table](/schema/postgres/enums.mdx#pg-create-enum-table).

Use table `user_role` as an enum table:

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "set_table_is_enum",
  "args": {
    "table": {
      "schema": "public",
      "name": "user_role"
    },
    "is_enum": true
  }
}
```

### Args syntax {#schema-metadata-set-table-is-enum-syntax}

| Key     | Required | Schema                                                | Description                                                              |
| ------- | -------- | ----------------------------------------------------- | ------------------------------------------------------------------------ |
| table   | true     | [TableName](/api-reference/syntax-defs.mdx#tablename) | Name of the table                                                        |
| is_enum | true     | Boolean                                               | Whether or not the table should be used as an `enum table <enum table>`. |

## track_table v2 {#schema-metadata-track-table-v2}

Version 2 of `track_table` is used to add a table/view to the GraphQL schema with configuration. You can customize the
root field names.

Add a table/view `author`:

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type": "track_table",
   "version": 2,
   "args": {
     "table": "author",
     "configuration": {
        "custom_root_fields": {
           "select": "Authors",
           "select_by_pk": "Author",
           "select_aggregate": "AuthorAggregate",
           "insert": "AddAuthors",
           "insert_one":"AddAuthor",
           "update": "UpdateAuthors",
           "update_by_pk": "UpdateAuthor",
           "delete": "DeleteAuthors",
           "delete_by_pk": "DeleteAuthor"
        },
        "custom_column_names": {
           "id": "authorId"
        }
     }
   }
}
```

A table can be tracked with a `custom name`. This can be useful when a table name is not GraphQL compliant, like
`Users Address`. A `custom name` like `users_address` will complement the `"Users Address"` table, so that it can be
added to the GraphQL schema.

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type": "track_table",
   "version": 2,
   "args": {
     "table": "Author Details",
     "configuration": {
        "custom_name": "author_details"
     }
   }
}
```

The GraphQL nodes and typenames that are generated will be according to the `identifier`. For example, in this case, the
nodes generated will be:

- `users_address`
- `users_address_one`
- `users_address_aggregate`
- `insert_users_address`
- `insert_users_address_one`
- `update_users_address`
- `update_users_address_by_pk`
- `delete_users_address`
- `delete_users_address_by_pk`

:::info Note

GraphQL Engine requires the constraint names (if any) of a table to be
[GraphQL compliant](https://spec.graphql.org/June2018/#sec-Names) in order to be able to track it.

:::

### Args syntax {#schema-metadata-track-table-syntax-v2}

| Key                      | Required | Schema                                                                          | Description                                   |
| ------------------------ | -------- | ------------------------------------------------------------------------------- | --------------------------------------------- |
| table                    | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                           | Name of the table                             |
| configuration            | false    | [Table Config](/api-reference/syntax-defs.mdx#table-config)                     | Configuration for the table/view              |
| apollo_federation_config | false    | [ApolloFederationConfig](/api-reference/syntax-defs.mdx#apollofederationconfig) | Apollo federation configuration for the table |

## set_table_custom_fields (deprecated) {#schema-metadata-set-table-custom-fields}

`set_table_custom_fields` has been deprecated. Use the
[set_table_customization](#schema-metadata-set-table-customization) API to set the custom table fields.

`set_table_custom_fields` in version `2` sets the custom root fields and custom column names of already tracked table.
This will **replace** the already present custom fields configuration.

Set custom fields for table/view `author`:

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type": "set_table_custom_fields",
   "version": 2,
   "args": {
     "table": "author",
     "custom_root_fields": {
        "select": "Authors",
        "select_by_pk": "Author",
        "select_aggregate": "AuthorAggregate",
        "insert": "AddAuthors",
        "insert_one":"AddAuthor",
        "update": "UpdateAuthors",
        "update_by_pk": "UpdateAuthor",
        "delete": "DeleteAuthors",
        "delete_by_pk": "DeleteAuthor"
     },
     "custom_column_names": {
        "id": "authorId"
     }
   }
}
```

### Args syntax {#schema-metadata-set-table-custom-fields-syntax}

| Key                 | Required | Schema                                                                  | Description                 |
| ------------------- | -------- | ----------------------------------------------------------------------- | --------------------------- |
| table               | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                   | Name of the table           |
| custom_root_fields  | false    | [Custom Root Fields](/api-reference/syntax-defs.mdx#custom-root-fields) | Customize the root fields   |
| custom_column_names | false    | [CustomColumnNames](/api-reference/syntax-defs.mdx#customcolumnnames)   | Customize the column fields |

## set_table_customization {#schema-metadata-set-table-customization}

`set_table_customization` allows you to customize any given table with a custom name, custom root fields and custom
column names of an already tracked table. This will **replace** the already present customization.

[set_table_custom_fields](#schema-metadata-set-table-custom-fields) has been deprecated in favour of this API.

Set the configuration for a table/view called `author`:

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
   "type": "set_table_customization",
   "args": {
     "table": "author_details",
     "configuration": {
       "identifier": "author",
       "custom_root_fields": {
          "select": "Authors",
          "select_by_pk": "Author",
          "select_aggregate": "AuthorAggregate",
          "insert": "AddAuthors",
          "insert_one":"AddAuthor",
          "update": "UpdateAuthors",
          "update_by_pk": "UpdateAuthor",
          "delete": "DeleteAuthors",
          "delete_by_pk": "DeleteAuthor"
       },
       "custom_column_names": {
          "id": "authorId"
       }
     }
   }
}
```

### Args syntax {#schema-metadata-set-table-customization-syntax}

| Key           | Required | Schema                                                     | Description                      |
| ------------- | -------- | ---------------------------------------------------------- | -------------------------------- |
| table         | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)      | Name of the table                |
| configuration | false    | [TableConfig](/api-reference/syntax-defs.mdx#table-config) | Configuration for the table/view |

## untrack_table {#schema-metadata-untrack-table}

`untrack_table` is used to remove a table/view from the GraphQL schema.

Remove a table/view `author`:

```http
POST /v1/query HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type": "untrack_table",
    "args": {
        "table": {
            "schema": "public",
            "name": "author"
         },
        "cascade": true
    }
}
```

### Args syntax {#schema-metadata-untrack-table-syntax}

| Key     | Required | Schema                                                | Description                                                                                                                        |
| ------- | -------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| table   | true     | [TableName](/api-reference/syntax-defs.mdx#tablename) | Name of the table                                                                                                                  |
| cascade | false    | Boolean                                               | When set to `true`, the effect (if possible) is cascaded to any Metadata dependent objects (relationships, permissions, templates) |
